/****************************************************************************
 *
 * ftsnames.h
 *
 *   Simple interface to access SFNT 'name' tables (which are used
 *   to hold font names, copyright info, notices, etc.) (specification).
 *
 *   This is _not_ used to retrieve glyph names!
 *
 * Copyright (C) 1996-2019 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */

#ifndef FTSNAMES_H_
#define FTSNAMES_H_

#include <ft2build.h>
#include FT_FREETYPE_H
#include FT_PARAMETER_TAGS_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif

FT_BEGIN_HEADER

/**************************************************************************
 *
 * @section:
 *   sfnt_names
 *
 * @title:
 *   SFNT Names
 *
 * @abstract:
 *   Access the names embedded in TrueType and OpenType files.
 *
 * @description:
 *   The TrueType and OpenType specifications allow the inclusion of a
 *   special names table ('name') in font files.  This table contains
 *   textual (and internationalized) information regarding the font, like
 *   family name, copyright, version, etc.
 *
 *   The definitions below are used to access them if available.
 *
 *   Note that this has nothing to do with glyph names!
 *
 */

/**************************************************************************
 *
 * @struct:
 *   FT_SfntName
 *
 * @description:
 *   A structure used to model an SFNT 'name' table entry.
 *
 * @fields:
 *   platform_id ::
 *     The platform ID for `string`.  See @TT_PLATFORM_XXX for possible
 *     values.
 *
 *   encoding_id ::
 *     The encoding ID for `string`.  See @TT_APPLE_ID_XXX, @TT_MAC_ID_XXX,
 *     @TT_ISO_ID_XXX, @TT_MS_ID_XXX, and @TT_ADOBE_ID_XXX for possible
 *     values.
 *
 *   language_id ::
 *     The language ID for `string`.  See @TT_MAC_LANGID_XXX and
 *     @TT_MS_LANGID_XXX for possible values.
 *
 *     Registered OpenType values for `language_id` are always smaller than
 *     0x8000; values equal or larger than 0x8000 usually indicate a
 *     language tag string (introduced in OpenType version 1.6).  Use
 *     function @FT_Get_Sfnt_LangTag with `language_id` as its argument to
 *     retrieve the associated language tag.
 *
 *   name_id ::
 *     An identifier for `string`.  See @TT_NAME_ID_XXX for possible
 *     values.
 *
 *   string ::
 *     The 'name' string.  Note that its format differs depending on the
 *     (platform,encoding) pair, being either a string of bytes (without a
 *     terminating `NULL` byte) or containing UTF-16BE entities.
 *
 *   string_len ::
 *     The length of `string` in bytes.
 *
 * @note:
 *   Please refer to the TrueType or OpenType specification for more
 *   details.
 */
typedef struct FT_SfntName_ {
	FT_UShort platform_id;
	FT_UShort encoding_id;
	FT_UShort language_id;
	FT_UShort name_id;

	FT_Byte *string;    /* this string is *not* null-terminated! */
	FT_UInt string_len; /* in bytes                              */

} FT_SfntName;

/**************************************************************************
 *
 * @function:
 *   FT_Get_Sfnt_Name_Count
 *
 * @description:
 *   Retrieve the number of name strings in the SFNT 'name' table.
 *
 * @input:
 *   face ::
 *     A handle to the source face.
 *
 * @return:
 *   The number of strings in the 'name' table.
 *
 * @note:
 *   This function always returns an error if the config macro
 *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
 */
FT_EXPORT(FT_UInt)
FT_Get_Sfnt_Name_Count(FT_Face face);

/**************************************************************************
 *
 * @function:
 *   FT_Get_Sfnt_Name
 *
 * @description:
 *   Retrieve a string of the SFNT 'name' table for a given index.
 *
 * @input:
 *   face ::
 *     A handle to the source face.
 *
 *   idx ::
 *     The index of the 'name' string.
 *
 * @output:
 *   aname ::
 *     The indexed @FT_SfntName structure.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   The `string` array returned in the `aname` structure is not
 *   null-terminated.  Note that you don't have to deallocate `string` by
 *   yourself; FreeType takes care of it if you call @FT_Done_Face.
 *
 *   Use @FT_Get_Sfnt_Name_Count to get the total number of available
 *   'name' table entries, then do a loop until you get the right platform,
 *   encoding, and name ID.
 *
 *   'name' table format~1 entries can use language tags also, see
 *   @FT_Get_Sfnt_LangTag.
 *
 *   This function always returns an error if the config macro
 *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
 */
FT_EXPORT(FT_Error)
FT_Get_Sfnt_Name(FT_Face face, FT_UInt idx, FT_SfntName *aname);

/**************************************************************************
 *
 * @struct:
 *   FT_SfntLangTag
 *
 * @description:
 *   A structure to model a language tag entry from an SFNT 'name' table.
 *
 * @fields:
 *   string ::
 *     The language tag string, encoded in UTF-16BE (without trailing
 *     `NULL` bytes).
 *
 *   string_len ::
 *     The length of `string` in **bytes**.
 *
 * @note:
 *   Please refer to the TrueType or OpenType specification for more
 *   details.
 *
 * @since:
 *   2.8
 */
typedef struct FT_SfntLangTag_ {
	FT_Byte *string;    /* this string is *not* null-terminated! */
	FT_UInt string_len; /* in bytes                              */

} FT_SfntLangTag;

/**************************************************************************
 *
 * @function:
 *   FT_Get_Sfnt_LangTag
 *
 * @description:
 *   Retrieve the language tag associated with a language ID of an SFNT
 *   'name' table entry.
 *
 * @input:
 *   face ::
 *     A handle to the source face.
 *
 *   langID ::
 *     The language ID, as returned by @FT_Get_Sfnt_Name.  This is always a
 *     value larger than 0x8000.
 *
 * @output:
 *   alangTag ::
 *     The language tag associated with the 'name' table entry's language
 *     ID.
 *
 * @return:
 *   FreeType error code.  0~means success.
 *
 * @note:
 *   The `string` array returned in the `alangTag` structure is not
 *   null-terminated.  Note that you don't have to deallocate `string` by
 *   yourself; FreeType takes care of it if you call @FT_Done_Face.
 *
 *   Only 'name' table format~1 supports language tags.  For format~0
 *   tables, this function always returns FT_Err_Invalid_Table.  For
 *   invalid format~1 language ID values, FT_Err_Invalid_Argument is
 *   returned.
 *
 *   This function always returns an error if the config macro
 *   `TT_CONFIG_OPTION_SFNT_NAMES` is not defined in `ftoption.h`.
 *
 * @since:
 *   2.8
 */
FT_EXPORT(FT_Error)
FT_Get_Sfnt_LangTag(FT_Face face, FT_UInt langID, FT_SfntLangTag *alangTag);

/* */

FT_END_HEADER

#endif /* FTSNAMES_H_ */

/* END */
